Workbench Design/WB Collection.iso/workbench werkzeuge/palette tools/colorsaver/colorsaver.guide

Amigaguide Document | 1996-04-07 | 23KB | 426 lines

@database ColorSaver.guide
@author "Dan Fish"
@(c) "Copyright
 1994 Dan Fish"
@$VER: ColorSaver.guide 1.18 (11/31/94)
@font topaz.font 8
@node MAIN "Colorsaver Info"
               @{bg highlight} +                 ColorSaver                 + @{bg back}
ColorSaver is a general purpose color palette tool designed to be available
at any time through the use of a hotkey.  It contains @{" Features " link
FEATURES} not generally
found in other palette tools
@{"    Disclaimer     " link DISCLAIMER      }   @{"   Distribution    " link DISTRIBUTION    }   @{" Acknowledgements  " link ACKNOWLEDGEMENTS}
@{"    Installing     " link INSTALLATION    }   @{"    Quick Test     " link QUICKTEST       }   @{"    Tool-Types     " link TOOLTYPES       }
@{"     Gadgets       " link GADGETS         }   @{"  ARexx Commands   " link AREXX           }   @{" Patching Binaries " link PATCHING        }
@{"     Author        " link AUTHOR          }   @{"     History       " link HISTORY         }   @{"      Bugs         " link BUGS            }
@endnode
@node FEATURES "ColorSaver Features"
@prev MAIN
@next DISCLAIMER
ColorSaver has the following features:
    * Implemented as a Commodity, Popup w/Hotkey
    * Load/Save color palettes
    * Sliders selectable between RGB/HSV
    * Copy, Swap, Range, Complement Functions
    * Left/right shifting of the entire palette
    * Ability to permanently alter (patch) the color tables of executables
      with a statically allocated color table.
    * "Remembers" load/save file path's through the life of the program
    * "Remembers" screen position it was last popped up to
    * Runs from CLI or WorkBench
    * ARexx Port with 15 commands
    * PostCardWare, Includes source
    * Tested with Enforcer
 See Also: @{" Mis-Features " link BUGS}   @{" ToDo " LINK TODO}
@endnode
@node DISCLAIMER "Disclaimer"
@prev FEATURES
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
               @{bg highlight} +                 WARNING!!!!!                 + @{bg back}
 *ANY* Program that directly patches executables is inherently dangerous!!
 (especially those that do so without making a temporary backup until the
 write completes, such as this one!!).  It is STRONGLY advised that when
 using the "WRITE" function, you do so ONLY on a backup (better yet, a backup
 of your backup!).  The end-user accepts any and all liability for results
 obtained through the use or misuse of this program, be it direct, indirect,
 consequential or incidental.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@endnode
@node INSTALLATION "Installing ColorSaver"
  Not much to it... If you always want ColorSaver available, drag its icon
  into the SYS:WBStartup drawer (Might want to set the CX_POPUP=NO tooltype)
  Also, if you want to save all your color palettes in the same location,
  then do one of the following:
    1. Set the "PATH=" ToolType  (I.E. PATH=SYS:Prefs/Colormaps)
    2. Set an environment variable for CS_PALETTES
       (I.E. SetEnv CS_PALETTES SYS:Prefs/Colormaps)
  (Otherwise ColorSaver will default to "SYS:Prefs" for load/save operations)
@endnode
@node DISTRIBUTION
 Every programmer likes to know that @{fg highlight}Somebody@{fg text} at least @{fg highlight}Somewhere@{fg text}
 uses their program... (plus they're also curious about how far from home
 the thing has gotten).   This program is @{b}PostCardWare.@{ub}
 If you use it, all I ask is that you let @{" me " link AUTHOR} know, by
 postcard or by Email
@endnode
@node TOOLTYPES "ColorSaver ToolTypes"
  ColorSaver has the following command-line/tooltype template:
     ColorSaver [CX_PRIORITY] [CX_POPUP] [CX_POPKEY] [CX_QUIT] [SELECT]
                [PATH] [POP_X] [POP_Y] [HSV]
     CX_PRIORITY/K/N,CX_POPUP/K,CX_POPKEY/K,CX_QUIT/K,SELECT/K/N, PATH/K,
     POP_X/K/N, POP_Y/K/N, HSV/S
     CX_PRIORITY    Sets ColorSaver's priority in the commodities queue.
            @{b}Default : 0 @{ub}
     CX_POPUP        When you specify "CX_POPUP=NO" window will not be
            opened when you initially start ColorSaver
            @{b}Default : YES @{ub}
     CX_POPKEY        Specifies the "HotKey" to Popup the ColorSaver window.
            @{b}Default : lalt ralt c @{ub}
     CX_QUIT        Specifies the "HotKey" to terminate ColorSaver
              @{b}Default : lalt ralt q @{ub}
     SELECT        Specifies the active Palette color when ColorSaver
                        is started
            @{b}Default : 0 @{ub}
     PATH        Specify the path for load/save operations
            @{b}Default : SYS:Prefs/Presets @{ub}
     POP_X        Specify the popup X position
            @{b}Default : 175 @{ub}
     POP_Y        Specify the popup Y position
            @{b}Default : 50 @{ub}
     HSV        If specified, ColorSaver will open with sliders set to
            HSV Mode.
            @{b}Default : Sliders set to "RGB" mode @{ub}
@endnode
@node GADGETS
 Gadget Descriptions:
 ~~~~~~~~~~~~~~~~~~~~~~
 Most of ColorSaver should be fairly Intuitive (no pun intended!) but for
 the sake of completeness, here's a description of the gadgetry.
 @{"    Load     " LINK LOAD_GAD}  @{"    Save     " LINK SAVE_GAD}  @{"    Write    " LINK WRITE_GAD}
 @{" Scan Binary " LINK SCAN_GAD}  @{"    Cycle    " LINK CYCLE_GAD}  @{"    Copy     " LINK COPY_GAD}
 @{"    Swap     " LINK SWAP_GAD}  @{"    Range    " LINK RANGE_GAD}  @{"
     " LINK SHIFTL_GAD}
 @{"
      " LINK SHIFTR_GAD}  @{" Complement  " LINK COMP_GAD}  @{"   RGB/HSV   " LINK RGBHSV_GAD}
 @{"
      " LINK INFO_GAD}  @{"    Okay     " LINK OKAY_GAD}  @{"     Do      " LINK DO_GAD}
 @{"    UnDO     " LINK UNDO_GAD}  @{"   Cancel    " LINK CANCEL_GAD}
@endnode
@node LOAD_GAD "Loading colormaps..."
 @{b}Load@{ub}        Load a saved colormap.  Load path/file is retained through
        the life of the program.  Load directory initially defaults
        to the "PATH=" tooltype (if specified) or the environment
                variable "CS_PALETTES" (if it exists) or "SYS:Prefs" if the
                previous two are undefined.  If the number of colors in the
                file do not match the depth of the current screen, you will
        be notified via requester and given a chance to "Cancel" or
        "Load Anyway".
         @{bg highlight} Keyboard ShortCut: @{bg back} Right-Amiga-L
@endnode
@node SAVE_GAD "Saving colormaps..."
 @{b}Save@{ub}        Save the current screen colors to a file for subsequent
        loading.  Save path/file is the same as that specified for
        LOAD.  Always saves number of colors associated with depth
        of the current screen.
                @{bg highlight} Keyboard ShortCut: @{bg back} Right-Amiga-S
@endnode
@node WRITE_GAD "Patching Binaries..."
@{b}Write@{ub}        Patch a binary file.  This gadget is disabled until a valid
        file offset (or offsets) is found using the @{"Scan Binary" LINK SCAN_GAD}
        function.  A requester will appear to confirm the file name
        and offset prior to the actual write.  If this is performed
        successfully, the color palette for the executable will be
        permanently modified.  See @{"Patching Binaries" LINK PATCHING}
@endnode
@node SCAN_GAD "Scanning a binary for a color palette"
 @{b}Scan Binary@{ub}    Scan a file for a sequence of bytes corresponding to the
        values of the Reset Palette.  The Reset Palette is that which
        exists at the time ColorSaver is first popped up, or after
        selecting @{" DO " LINK DO_GAD}.  See @{" Patching Binaries " LINK PATCHING}
@endnode
@node CYCLE_GAD "Selecting a file offset..."
 @{b}Cycle Gadget@{ub}    Displays valid file offsets.  This gadget is disabled until
        a valid file offset (or offsets) is found using the @{"Scan Binary" LINK SCAN_GAD}
        function.  In the event more than one match is found, multiple
        file offsets will be listed.  The selected offset will be that
        used for a @{" WRITE " LINK WRITE_GAD} operation.  See @{" Patching Binaries " LINK PATCHING}
@endnode
@node COPY_GAD "Copying palette colors..."
 @{b}Copy@{ub}        Copy the currently selected color to the color next selected on
        the color palette.
@endnode
@node SWAP_GAD "Swapping palette colors..."
 @{b}Swap@{ub}        Swaps the currently selected color with the color next selected
        on the color palette.
@endnode
@node RANGE_GAD "Spreading palette colors..."
 @{b}Range@{ub}        Spread the colors between the currently selected color and the
        color next selected on the color palette.  A least one inter-
        vening color must exist between the two colors or this selec-
        tion will have no effect.
@endnode
@node SHIFTL_GAD "Shifting the entire palette left..."
 @{b}
@{ub}        Shift the entire color palette left. (I.E. Color 1 becomes
        color 0, color 2 becomes color 1, ...etc)
@endnode
@node SHIFTR_GAD "Shifting the entire palette right..."
 @{b}
@{ub}        Shift the entire color palette right. (I.E. Color 1 becomes
        color 2, color 0 becomes color 1, ...etc)
@endnode
@node COMP_GAD "Complementing the currently selected color..."
 @{b}Complement@{ub}    Complements the currently selected color.
@endnode
@node RGBHSV_GAD "Changing palette slider functions..."
 @{b}RGB/HSV@{ub}    Change slider functions between RGB and HSV.  This will be
        "remembered" between subsequent ColorSaver "popup's".
@endnode
@node INFO_GAD "Display program info..."
 @{b}
@{ub}        Displays some info about the program.
@endnode
@node CANCEL_GAD "Cancelling changes..."
 @{b}Cancel@{ub}        Cancels all color changes and restores palette in effect when
        ColorSaver was popped up.  Closes the ColorSaver window.
                @{bg highlight} Keyboard ShortCut: @{bg back} Right-Amiga-C
@endnode
@node UNDO_GAD "Undo'ing changes..."
 @{b}UnDO@{ub}        Exactly the same as @{" CANCEL " LINK CANCEL_GAD} except window is left open for
        "further diddling".
                @{bg highlight} Keyboard ShortCut: @{bg back} Right-Amiga-U
@endnode
@node OKAY_GAD "Accepting changes..."
 @{b}Okay@{ub}        Accepts the current color settings and closes the ColorSaver
        window.
                @{bg highlight} Keyboard ShortCut: @{bg back} Right-Amiga-O
@endnode
@node DO_GAD "Implementing changes..."
 @{b}Do@{ub}        Exactly the same as @{" OKAY " LINK OKAY_GAD} except ColorSaver window is left
        open.  Used mainly to force the current palette into the reset
        palette without having to close and re-open the window.
@endnode
@node AREXX "ARexx Commands"
 ARexx Commands:
 ~~~~~~~~~~~~~~~
 The ARexx command set is still minimal, error checking is near nil, both should
 improve with the next release.  Some example scripts have been supplied that show
 most of the trickier functions.  If you come up with some really innovative
 Arexx uses of ColorSaver, I'd be interested in hearing about them and will include
 them in the next release (Along with credits of course;).
 Note: All screen references refer to IntuitionBase->FirstScreen.  At
       present, there is no way to specify the screen name.
    SHOW   -- Popup the ColorSaver window
    HIDE   -- Hides the ColorSaver window
    CANCEL -- Cancels any color changes since the window was popped up or
          since a STOREPALETTE operation.
    QUIT   -- Kills ColorSaver
    LOAD <Filename> -- Loads a palette.  If "Filename" does not contain
              a path, the path will default to that specified in an
          environment variable or tooltype.  See the @{" Load " LINK LOAD_GAD} gadget
          Note: Unlike with the "Load" gadget, the ARexx version of
                        LOAD will give you no notification if the colors in
            the file do not match the screen depth.  It will
            simply do a "Load Anyway".
    SAVE <Filename> -- Saves the screen palette.  Always saves the number
                  of colors associated with the depth of the screen.  If "Filename"
                  does not contain a path, the path will default to that specified
                  in an environment variable or tooltype.  See the @{" Save " LINK SAVE_GAD} gadget
    STOREPALETTE --  Saves the current screen palette which is restored with
                         a CANCEL operation.
    SHIFTL -- Shift the entire color palette left. (I.E. Color 1 becomes
        color 0, color 2 becomes color 1, ...etc)  See the @{"
 " LINK SHIFTL_GAD} gadget
    SHIFTR -- Shift the entire color palette left. (I.E. Color 1 becomes
        color 2, color 2 becomes color 3, ...etc)  See the @{"
 " LINK SHIFTR_GAD} gadget
    RGBMODE  -- Set sliders to RGB mode.  See  @{" RGB/HSV " LINK RGBHSV_GAD}
    HSVMODE  -- Set sliders to HSV mode.  See  @{" RGB/HSV " LINK RGBHSV_GAD}
                    Note: at present there is no way to actually set specific HSV
                          values from ARexx.  All values must be specified in
                          RGB using the SETRGB command.  If HSVMODE is selected
                          however, and the ColorSaver window is open, the HSV
                          sliders will be set to the correct values.
    NUMCOLORS -- Returns in the ARexx RESULT variable, the number of colors
             (corresponding to the depth of) the screen.
    SELECT <#> -- Selects color specified by <#> as the active color. Where:
                      <#> = 0 to "NUMCOLORS-1"
    GETRGB -- Returns in the ARexx RESULT variable, 3 numbers specifying
                  the current R G B Values of the active color for the screen
    SETRGB [C=#] [R=#] [G=#] [B=#] -- Set the RGB values for a specific color
                register, where:
            C = (Color) 0 to "NUMCOLORS-1"
            R = (Red)   0 to 15
            G = (Green) 0 to 15
                        B = (Blue)  0 to 15
        Parameters not specified will retain their current values.
@endnode
@node Author "WhoDunnit..."
 Please send bug reports, suggestions, comments and/or PostCards to:
    Dan Fish
    815 E. Bethany #B135
    Phoenix, AZ.  85014
    Email: [e-mail]       (preferred)
               [e-mail]    (if above undeliverable)
@endnode
@node PATCHING "Patching Binaries
 Ever have this happen to you?  You start this brand new program and say:
 "Yeah, this is nice, but the person's choice of colors is really awful!"
 Everybody has different tastes in colors, so what do you do?  Well, if you're
 lucky, the programmer was thoughtful enough to put in a palette for you to
 change them with, and if you're *REAL* lucky he was even kind enough to allow
 you to save them somewhere as the default! (I must at admit, many programs
 are at least getting much better about including a palette tool.. :-)
 So... no palette tool, Huh?  Well, that's where ColorSaver can @{" sometimes " link SOMETIMES} give
 you a hand... Just run your program, popup ColorSaver, Click on the "Scan
 Binary" gadget and select the filename for your program.  ColorSaver will
 attempt to locate the "palette" inside the binary.  If it finds one (or more)
 it will let you know, and will activate the "Write" and "Offset" gadgets.
 Now all you need to do is change the colors to your liking and click on
 "Write".  Poof!  For ever-after when you run that program, it will have the
 colors you selected.
 As proof that this really does work, I've included a small "test" program
 called "ColorTest".  Simply run ColorTest, popup ColorSaver, use it to scan
 ColorTest and it should come back with (1) color table match at offset 4196.
 Change the colors to your liking, "Write" them, select Cancel or Okay from
 ColorSaver, (Doesn't matter which, you've already written the colors) and
 then exit ColorTest.  Now when you run ColorTest again, it will have the
 colors you selected.
 Magic, Huh?  Naw, not really. I've been doing the same thing for years with a
 hex editor, ColorSaver just makes it much easier.  Note that I said earlier
 that "ColorSaver can @{" sometimes " link SOMETIMES} help..."
@endnode
@node SOMETIMES "Well.... SOMETIMES it works!"
  And now the bad news... this won't work with all programs...
 Generally, the table must be statically allocated in the source.  I.E.
 something like:
    UWORD colortable[]     = { 0x000, 0xf44, 0x4f4, 0x44f };
 When you run your program and pop up ColorSaver, it gets the current palette
 and when you do a "Scan Binary" it looks for that sequence of bytes in the
 file and will replace them with the colors you choose.
 If a program uses individual calls to SetRGB4(), dynamic allocation, does
 color cycling or other strange things, this won't work.  I'd estimate I've
 been able to sucessfully alter the palettes of somewhere between 1/3 and 1/2
 the binaries I've tried it on.
 It is possible that there could be more than one sequence of matching bytes
 (particularly with 1 and 2 bitplane programs.  If this is the case, then
 (for now anyway) you'll have to "roll the dice" and write to one of the
 locations.  @{fg highlight} BE ABSOLUTELY, POSITIVELY SURE YOU DO THIS ONLY ON A BACKUP OF
A BACKUP OF A BACKUP OF THE PROGRAM!!! @{fg text} (hope you read the @{" Disclaimer " link DISCLAIMER})
 If you then run your program and get a free trip to India, you'll know you
 selected the wrong one!  (Perserverance is the key here!).
 Personally I've only run across this a couple of times, and I think they
 were both 1 bitplane black & white screens.
 Note that you are not really limited to scanning and writing to executables,
 you can also scan binary data and/or configuration files. (or even the color
 palettes saved by ColorSaver!)
@endnode
@node HISTORY "ColorSaver History..."
 31-Nov-94  Version 1.18
        - ARexx improvements
        - Added custom pointers
            - Added Close/Hide Requester upon clicking the close gadget
 25-Aug-94  Version 1.10
        - Code getting rather large for one file, split into several
          smaller files
            - Converted/updated documentation to AmigaGuide format

 18-Feb-94  Version 1.02
            - Minor code changes not affecting operation
 19-Sep-93  Version  1.0
            (Very few bug reports/suggestions, so found my own...)
            (Does anybody but me ACTUALLY use this thing??)
            - Fixed irritation that caused "Complement" not to
          work under OS3.0
            - Cleaned up the source a bit.
            - Added the following tooltypes:
                SELECT -- Specify the active color on startup
                PATH   -- Specify the load/save file path
                POP_X  -- Specify the popup X position
                POP_Y  -- Specify the popup Y position
        - Added rudimentary ARexx port
 06-Jun-93  Version 0.86
            - Bug Fixed, Called UnlockPubScreen() even though I
          never called LockPubScreen()
        - Bug Fixed, If "Load Anyway" selected when loading
              colors of < depth of frontscreen, will now only
              change the actual number of colors loaded.
 05-Jan-93  Version 0.84
            - Alpha Release  (First Public Release)
@endnode
@node ACKNOWLEDGEMENTS
 Acknowledgements:
 ~~~~~~~~~~~~~~~~~~
    * Many thanks to Jan van den Baard for his excellent "GadToolsBox"
      which makes the task of writing programs such as this so much
      easier, and for providing the well documented, structured source
      for JBSpool (FF656).  (Most of the commodity stuff for ColorSaver
      was yanked out of JBSpool, and I hope he doesn't mind me including
      his link library "dcbacks.lib", though I could find no limitations
      to distribution in his documentation).
    * Also many thanks to Matt Dillon and the folks at Obvious
      Implementations Corp. for the excellent DICE environment.
    * And of course, thanks to Fred, his library, and all the hundreds of
      talented people who have submitted very high quality programs, with-
      out which the Amiga might very well still be just "An Interesting
      Curiosity" ....as was the Atari ST!
@endnode
@node QUICKTEST
For those of you who hate long-winded documentation, (don't we all??) here's
some quick exercises to show off ColorSaver.  (Note: Use LAlt-RAlt-C to
"popup" ColorSaver)
   1. Double-Click on ColorSaver, select "Load", you should have a choice of
      several palettes, Try loading a couple...  You can also fiddle with the
      colors, then save your own palette.  (Probably have to save it somewhere
      else, or write-enable the disk!)
   2. When you get tired of that, you can try out ColorSaver's binary file
      patching ability.
      a.) Double-Click on "ColorTest" and note the colors (black & white with
      a single red bar)
      b.) Popup ColorSaver and adjust the colors until you like them.
      c.) Select "Scan-Binary"
      d.) Select "ColorTest" from the file requester.
      e.) ColorSaver should respond that it found one Color Table match
      (Cycle gadget should display offset of 4196)
      f.) Select "Write" and confirm the requester (probably have to
      write-enable the disk if you haven't copied all the files somewhere)
      g.) Hide ColorSaver (select "Cancel")
      h.) Exit ColorTest
      Now run ColorTest again and note that the colors have been permanently
      and forever changed to the ones you selected.  (Or at least until you
      run ColorSaver again!)
   3. Try out the various supplied ARexx scripts.
@endnode

@node BUGS "Notes (and other Bugs...;(
 The following are known ...um, er, Peculiarities!
    * Does not properly handle HAM palettes
    * Loading "non-palette" files should not be fatal, but will result
      in "bizarre" color schemes (that will likely include the pointer)
    * Does not use LockPubScreen(), Had problems with this, instead
      ColorSaver pops up on IntuitionBase->FirstScreen, thus you should
      avoid closing a screen that you have ColorSaver popped up on.
      (Close ColorSaver window FIRST!)
    * Popping up the palette on some screens with unusual color settings
      may render ColorSaver nearly (or totally) invisible.
    * If something other than ColorSaver is responsible for changing the
      colors of a screen, (I.E. another palette tool, system calls, etc.),
      the sliders will become "out of sync" with the current screen colors,
      Clicking on a slider will cause that color to "jump back" to what
      ColorSaver thinks it should be.  You can avoid this effect by making
      a palette selection.  This will cause ColorSaver to reset the
      sliders to the CURRENT screen colors.  (This effect is probably
      normal for all palette tools).
@endnode
@node TODO "Future plans..."
 Some possible enhancements:
    * Localization of the Gadgetry
    * Enhance ARexx command set, better error checking
    * Screen selection by name
    * Recognize/Load/Save SYS:Prefs/Presets type palettes
    * Better handling of palettes with a large number of colors,
      (I.E. With 128-256 colors, you currently need a magnifying
           glass to select the proper color...;)
@endnode